
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Xml;
using Swaf.Call;
using Swaf.Container;
using Swaf.Config;

namespace Swaf.Security
{
	/// <summary>
	/// The ISecurityManager interface specifies the properties and methods 
	/// that are common to any Security Manager implementation. 
	/// </summary>
	/// <remarks>
	/// The Swaf Framework Security feature provides an �out of the box� 
	/// security implementation that is adaptable to any CSF application.  The 
	/// design allows for easy extensibility and addresses the basic security 
	/// needs of most applications.  As with all CSF features, the security 
	/// feature in configuration driven and is based on solid use of design 
	/// patterns and practices.
	/// 
	/// The new Security Manager component of CSF is treated as a �first class citizen� 
	/// such as the Rule Manager, BizObj Manager or Resource Manager.  As such, this 
	/// class can be referenced directly off the IApplication interface and will always 
	/// be present within a CSF application.  For backward compatibility,  the base 
	/// Swaf assembly ships with a default security implementation that basically 
	/// acts as a pass through allowing existing applications which already have a security 
	/// implementation to upgrade without modifying existing code.
	/// 
	/// Rather than focusing on the management aspects of security, this design focuses 
	/// only on the underlying security mechanisms for securing resources within a CSF 
	/// application.  As such, all constructs such as roles, groups, etc are not addressed.  
	/// Instead, the design focuses on the privileges which are derived from these management 
	/// constructs for each secured resource.  The business logic level code, implemented by 
	/// the development team using this feature, is responsible for mapping management 
	/// constructs such as roles onto resources and providing the basic privileges available 
	/// for that resource for each user.
	/// 
	/// The design does allow for nested or hierarchical relationships between resources.  
	/// A good example of such a relationship is that between a page or view and the UI 
	/// elements contained on that view.  The design supports using deep name address 
	/// support to drill down through the layers of resources and allow each layer to 
	/// increase, decrease or completely override the returned privileges from an associated 
	/// or contained resource.
	/// 
	/// Another key feature of this design is the approach to revoking privileges.  
	/// This design does not address negative or subtractive privileges due to the 
	/// complexities associated with that approach.  The absence of a resource in the 
	/// list denotes a privilege of �None.�  As a result, the methods associated with 
	/// each group of resources should not return any resources for which the current 
	/// user does not have access.

	/// </remarks>
	public interface ISecurityManager
	{
		/// <summary>
		/// The resourceSets read-only property of this class provides a reference to 
		/// the global collection of resourceSet objects defined for an application.  
		/// These resourceSets are defined in the application�s feature file and loaded 
		/// once at application startup.  The objects referenced by the SecurityManager 
		/// are only the �shells� and do not contain populated resources.  They do, 
		/// however contain an instance of the associated ICall class that is used 
		/// to populated the associated resources by the security principal.  The 
		/// security principal instance will clone these resourceset objects to seed 
		/// its resourceSets collection.
		/// </summary>
		INameAddressSupport resourceSets{get;}

		/// <summary>
		/// The currentPrincipal property sets or gets the ISecurityPrincipal instance 
		/// for the current global application object.  This principal will be used for 
		/// any rule execution that executes outside of a SessionApplication instance 
		/// or is decorated with the security=�global� attribute.
		/// </summary>
		ISecurityPrincipal currentPrincipal{get;set;}

		/// <summary>
		/// <summary>
		/// The createPrincipal method provides the logic to instantiate a new security 
		/// principal class.  The actual security principal class instantiated is 
		/// determined by the SecurityPrincipal configuration element which contains 
		/// the fully qualified class name to be instantiated by createPrincipal.  
		/// This method takes three arguments, a UserName string, an additionalInfo 
		/// INameAddressSupport class instance (FlexiMap) with elements containing 
		/// relevant, application specific security information and an ICall instance 
		/// used to retrieve the roles for this principal.
		/// <param name="UserName">The name of the current user</param>
		/// <param name="additionalInfo">INameAddressSupport instance (FlexiMap or BizObj)
		/// containing relevant, application specific information about the user</param>
		/// <param name="RolesCal">ICall instance used to return the list of roles for this user</param>
		/// <returns></returns>
		ISecurityPrincipal createPrincipal(string UserName, INameAddressSupport additionalInfo, ICall rolesCal);

		/// <summary>
		/// The createPrincipal method provides the logic to instantiate a new security 
		/// principal class.  The actual security principal class instantiated is 
		/// determined by the SecurityPrincipal configuration element which contains 
		/// the fully qualified class name to be instantiated by createPrincipal.  
		/// This method takes one argument, a principalInfo 
		/// INameAddressSupport class instance (FlexiMap) with elements containing 
		/// relevant, application specific security information and, at a minimum, 
		/// a UserName field.
		/// </summary>
		/// <param name="principalInfo">INameAddressSupport instance constaining 
		/// additional, application specific information about the current user</param>
		/// <returns></returns>
		ISecurityPrincipal createPrincipal(INameAddressSupport principalInfo);

		/// <summary>
		/// The createPrincipal method provides the logic to instantiate a new security 
		/// principal class.  The actual security principal class instantiated is 
		/// determined by the SecurityPrincipal configuration element which contains 
		/// the fully qualified class name to be instantiated by createPrincipal.  
		/// This method takes one argument, an Xml configurattion node containing serialized
		/// principal information.
		/// </summary>
		/// <param name="principalEle">Xml configuration node containing serialized principal information</param>
		/// <returns></returns>
		ISecurityPrincipal createPrincipal(XmlElement principalEle);

		/// <summary>
		/// The defaultRolesCall readonly property returns the ICall instance for retrieving a 
		/// principal's roles.  This value is set during program initialization by the configuration 
		/// system.
		/// </summary>
		ICall defaultRolesCall{get;}
		/// <summary>
		/// This method is used to establish a remote principal using serializable information.
		/// </summary>
		/// <param name="UserName"></param>
		/// <param name="additionalInfo"></param>
		void setCurrentPrincipal(string UserName, INameAddressSupport additionalInfo, string instanceId);
	}
}
